#region License

// This file is part of Grawlix.
// 
// Grawlix is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as
// published by the Free Software Foundation, either version 3 of
// the License, or (at your option) any later version.
// Grawlix is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public
// License along with Grawlix.  If not, see
// <http://www.gnu.org/licenses/>.

#endregion

using System;
using System.IO;

namespace Grawlix.Services.Resources
{
	/// <summary>
	/// A service that resolves URIs of a specific scheme.
	/// </summary>
	public interface IUriResolver
	{
		/// <summary>
		/// Completes the given uri with the default scheme.
		/// </summary>
		/// <param name="uri">The URI to complete. Can be absolute
		/// (will have no effect).</param>
		/// <returns>A completed URI.</returns>
		Uri CompleteUri(Uri uri);

		/// <summary>
		/// Determines whether the specified scheme is supported.
		/// </summary>
		/// <param name="scheme">The URI scheme to test.</param>
		/// <returns>
		/// 	<c>true</c> if the specified scheme is supported;
		/// 	otherwise, <c>false</c>.
		/// </returns>
		bool IsSupported(string scheme);

		/// <summary>
		/// Loads an embedded resource or Stream by its URI.
		/// </summary>
		/// <param name="uri">The URI that identifies the embedded
		/// resource.</param>
		/// <returns>The embedded resource or Stream found.</returns>
		/// <exception cref="IOException">A generic I/O error occurred.
		/// </exception>
		/// <exception cref="FileNotFoundException">The URI could not
		/// be resolved or does not point to an embedded resource.
		/// </exception>
		/// <remarks>This is a blocking operation which should only be
		/// called asynchronously.</remarks>
		/// <exception cref="ArgumentException">The URI scheme is not
		/// supported.</exception>
		object Load(Uri uri);

		/// <summary>
		/// Tries to load an embedded resource or Stream by its URI.
		/// </summary>
		/// <param name="uri">The URI that identifies the embedded
		/// resource.</param>
		/// <returns>The embedded resource or Stream found, or null if
		/// none found.</returns>
		/// <exception cref="IOException">A generic I/O error occurred.
		/// </exception>
		/// <remarks>This is a blocking operation which should only be
		/// called asynchronously.</remarks>
		/// <exception cref="ArgumentException">The URI scheme is not
		/// supported.</exception>
		object TryLoad(Uri uri);

	}
}